Wire Protocol (J.REP)

Payload Structure

All wire messages sent across are assumed to be JSON arrays at the outermost element, contained in which, there are 0..n messages. An empty array is considered a no-operation, but should be counted as activity against any idle timeout limit between federated buses.

Figure 1 - Example J.REP Payload

[
  {"ToSubject" : "SomeEndpoint", "Value" : "SomeValue" },
  {"ToSubject" : "SomeOtherEndpoint", "Value" : "SomeOtherValue"}
]

In Figure 1, we see an example of a J.REP payload containing two messages. One bound for an endpoint named "SomeEndpoint" and the other bound for the endpoint "SomeOtherEndpoint". They both include a payload element "Value" which contain strings. Let's take a look at the anatomy of an individual message.

Figure 2 - An J.REP Message

{
  "ToSubject" : "TopicSubscriber",
  "CommandType" : "Subscribe",
  "Value " : "happyTopic",
  "ReplyTo" : "MyTopicSubscriberReplyTo"
}

The message shown in Figure 2 shows a very vanilla J.REP message. The keys of the JSON Object represent individual message parts, with the values representing their corresponding values. The standard J.REP protocol encompasses a set of standard message parts and values, which for the purposes of this specification we'll collectively refer to as the protocol verbs.

The following table describes all of the message parts that a J.REP capable client is expected to understand:

Part	Required	JSON Type	Description
`ToSubject`	Yes	String	Specifies the subject within the bus, and its federation, which the message should be routed to.
`CommandType`	No	String	Specifies a command verb to be transmitted to the receiving subject. This is an optional part of a message contract, but is required for using management services
`ReplyTo`	No	String	Specifies to the receiver what subject it should reply to in response to this message.
`Value`	No	Any	A recommended but not required standard payload part for sending data to services
`PriorityProcessing`	No	Number	A processing order salience attribute. Messages which specify priority processing will be processed first if they are competing for resources with other messages in flight. Note: the current version of ErraiBus only supports two salience levels (0 and >1). Any non-zero salience in ErraiBus will be given the same priority relative to 0 salience messages
`ErrorMessage`	No	String	An accompanying error message with any serialized exception
`Throwable`	No	Object	If applicable, an encoded object representing any remote exception that was thrown while dispatching the specified service

Built-in Subjects

The table contains a list of reserved subject names used for facilitating things like bus management and error handling. A bus should never allow clients to subscribe to these subjects directly.

Subject	Description
`ClientBus`	The self-hosted message bus endpoint on the client
`ServerBus`	The self-hosted message bus endpoint on the server
`ClientBusErrors`	The standard error receiving service for clients

As this table indicates, the bus management protocols in J.REP are accomplished using self-hosted services. See the section on Bus Management and Handshaking Protocols for details.

Message Routing

There is no real distinction in the J.REP protocol between communication with the server, versus communication with the client. In fact, it assumed from an architectural standpoint that there is no real distinction between a client and a server. Each bus participates in a flat-namespaced federation. Therefore, it is possible that a subject may be observed on both the server and the client.

One in-built assumption of a J.REP-compliant bus however, is that messages are routed within the auspices of session isolation. Consider the following diagram:

images/author/download/attachments/23036473/FederationTopology.png
Figure 3 - Topology of a J.REP Messaging Federation

In Figure 3, is is possible for Client A to send messages to the subjects ServiceA and ServiceB. But it is not possible to address messages to ServiceC. Conversely, Client B can address messages to ServiceC and ServiceB, but not ServiceA.

Bus Management and Handshaking Protocols

Federation between buses requires management traffic to negotiate connections and manage visibility of services between buses. This is accomplished through services named ClientBus and ServerBus which both implement the same protocol contracts which are defined in this section.

ServerBus and ClientBus commands

Both bus services share the same management protocols, by implementing verbs (or commands) that perform different actions. These are specified in the protocol with the CommandType message part. The following table describes these commands:

Command / Verb	Message Parts	Description
`ConnectToQueue`	N/A	The first message sent by a connecting client to begin the handshaking process.
`CapabilitiesNotice`	`CapabilitiesFlags`	A message sent by one bus to another to notify it of its capabilities during handshake (for instance long polling or websockets)
`FinishStateSync`	N/A	A message sent from one bus to another to indicate that it has now provided all necessary information to the counter-party bus to establish the federation. When both buses have sent this message to each other, the federation is considered active.
`RemoteSubscribe`	`Subject` or `SubjectsList`	A message sent to the remote bus to notify it of a service or set of services which it is capable of routing to.
`RemoteUnsubscribe`	`Subject`	A message sent to the remote bus to notify it that a service is no longer available.
`Disconnect`	`Reason`	A message sent to a server bus from a client bus to indicate that it wishes to disconnect and defederate. Or, when sent from the client to server, indicates that the session has been terminated.
`SessionExpired`	N/A	A message sent to a client bus to indicate that its messages are no longer being routed because it no longer has an active session
`Heartbeat`	N/A	A message sent from one bus to another periodically to indicate it is still active.

Message Parts for Bus Commands: